---
layout: docs
page_title: Simple Certificate Enrollment Protocol (SCEP)
description: >-
   Configure the PKI plugin to work with Simple Certificate Enrollment Protocol (SCEP).
---

> [!IMPORTANT]  
> **Documentation Update:** Product documentation, which were located in this repository under `/website`, are now located in [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs), colocated with all other product documentation. Contributions to this content should be done in the `web-unified-docs` repo, and not this one. Changes made to `/website` content in this repo will not be reflected on the developer.hashicorp.com website.

# Configure a Simple Certificate Enrollment Protocol (SCEP)

@include 'alerts/enterprise-only.mdx'

SCEP is an IETF standardized protocol ([RFC 8894](https://datatracker.ietf.org/doc/html/rfc8894))
that allows clients to acquire client certificates and associated
Certificate Authority (CA) certificates. You can configure the PKI plugin to
use [SCEP](https://datatracker.ietf.org/doc/html/rfc8894) authentication.

## Before you start

- **You must have Vault Enterprise 1.20 or later**.
- **You must use the `static-challenge` authentication type to work with JAMF Pro.**
- **To use multiple authentication methods, you must have separate PKI mounts**.
  The SCEP implementation only allows one type of challenge authentication for
  a given PKI mount. If you require multiple authentication methods, you must
  create separate PKI mounts, that point to either a shared SCEP auth mount or
  separate SCEP auth mounts.

## Step 1: Determine your authentication methods

The Vault SCEP implementation supports a few different authentication mechanisms in
two categories.

 * Challenge Based authentication
   - [Intune authentication](/vault/docs/auth/scep)
   - [Static challenge authentication](/vault/docs/auth/scep)
 * [Certificate Authentication](/vault/docs/auth/cert)

For SCEP challenge based authentication, one of either static challenge or Intune mechanisms
can be used to authenticate clients within a given PKI mount. This is controlled
by configuring Intune within the PKI mount's SCEP configuration, otherwise we fallback
to using static challenges.

Certificate authentication can optionally be used for requests without a challenge value.
This is useful for clients that are renewing their certificate without
requiring the original challenge value.

The static challenge and Intune authentication mechanisms use a dedicated SCEP
authentication mount within the same namespace, while the certificate authentication
mechanism uses a configured certificate authentication mount. Both of these mounts
are used to validate the client provided credentials along with the client's ACL policy.

For proper accounting, mounts supporting SCEP authentication should be
dedicated to this purpose, and should not be shared with other workflows. In other words,
create a new auth mount for SCEP even if you already have one of the same
type for other purposes.

When setting up the authentication mount for SCEP clients, the token type must
be configured to return [batch tokens](/vault/docs/concepts/tokens#batch-tokens).
Batch tokens are required to avoid an excessive amount of leases being generated
and persisted as every SCEP incoming request needs to be authenticated.

If using the `sign-verbatim` or `role:my-role-name` as a path policy, the following
ACL policy will allow an authenticated client access the required PKI SCEP paths.
```hcl
path “pki/scep” {
  capabilities=[“read“, “update”, “create”]
}
path “pki/scep/pkiclient.exe” {
  capabilities=[“read“, “update”, “create”]
}
```

For a role base path policy, this sample policy can be used
```hcl
path “pki/roles/my-role-name/scep” {
  capabilities=[“read“, “update”, “create”]
}
path “pki/roles/my-role-name/scep/pkiclient.exe” {
  capabilities=[“read“, “update”, “create”]
}
```

##### Sample SCEP authentication mounts

```shell-session
$ vault auth enable scep
$ vault write auth/scep/role/static-challenge-1 \
      auth_type="static-challenge" \
      challenge=${SCEP_PASS} \
      token_policies="access-scep" \
      token_type="batch"
```

```shell-session
$ vault auth enable cert
$ vault write auth/cert/certs/scep-ca \
      display_name="SCEP Client CA" \
      token_policies="access-scep" \
      certificate="${CERTIFICATE}" \
      token_type="batch" \
      allowed_common_names="${HOSTNAME}"
```

```shell-session
$ vault write auth/scep/role/intune \
     auth_type="intune" \
     token_policies="access-scep" \
     token_type="batch"
```

## Step 2: Tune your PKI mount parameters

Once the authentication mount has been created and configured, the authentication mount's accessor
will need to be captured and added within the PKI mount's [delegated auth accessors](/vault/api-docs/system/mounts#delegated_auth_accessors).

To get an authentication mount's accessor field, the following command can be used.

```shell-session
$ vault read -field=accessor sys/auth/scep
$ vault read -field=accessor sys/auth/cert
```

These field accessors are then added to the mount's delegated auth accessors.

```shell-session
$ vault secrets tune \
  -delegated-auth-accessors="auth_scep_e2f4f6d5" \
  -delegated-auth-accessors="auth_cert_4088ac2d" \
  pki
```

## Step 3: Configure your SCEP authentication mount


<Tabs>

<Tab heading="Static challenge">

The following example uses two different authentication methods: certificates
and a static secret SCEP authentication.

The `default_path_policy` uses the existing `scep-clients` PKI role for
restrictions and defaults, leveraging the issuer specified within the role.

```shell-session
vault write pki_int/config/scep -<<EOC
{
  "enabled": true,
  "default_path_policy": "role:scep-clients",
  "authenticators": {
    "scep": {
      "accessor": "${SCEP_ACCESSOR}",
      "scep_role": "static-challenge-1"
    },
    "cert": {
      "accessor": "${CERT_ACCESSOR}",
      "cert_role": "scep-ca"
    }
  }
}
EOC
```

A PKI mount can use different static challenge values. In that case, the SCEP
auth mount must have multiple `static-challenge` roles configured, each with a
different `challenge` value. And the PKI mount configuration must leave
`scep_role` field blank so Vault tries PKI mount login attempts against all
available SCEP authentication roles.

</Tab>

<Tab heading="Intune">

The following example uses SCEP with Intune authentication. Note that the
SCEP auth mount must have a role configured with `auth_type` set to `intune`.
You can choose to set your Intune authentication credentials explicilty in the
configuraiton, as environment variables, or leverage Azure managed identities.

All the `intune` specific fields within the `external_validation` block also
accept [indirect value references](/vault/docs/configuration/seal#indirect-value-references).

```shell-session
vault write pki_int/config/scep -<<EOC
{
  "enabled": true,
  "default_path_policy": "role:scep-clients",
  "authenticators": {
    "scep": {
      "accessor": "${SCEP_ACCESSOR}",
      "scep_role": "intune"
    }
  }
  "external_validation": {
    "intune": {
      "tenant_id": "${INTUNE_TENANT_ID}",
      "client_id": "${INTUNE_CLIENT_ID}",
      "client_secret": "${INTUNE_CLIENT_SECRET}"
    }
  }
}
```

<Note>

During internal testing, we noticed Intune clients fail to match the CA
certificate when the GetCACerts request returned a full certificate chain
instead of the issuer CA certificate by itself.

If you experience issues with GetCACerts requests, you can set the
`restrict_ca_chain_to_issuer` field in your PKI mount SCEP configuration to
`true`. Restricting the CA chain forces SCEP to only return the issuer CA
certificate.

</Note>

</Tab>

</Tabs>




## Resources

- [PKI secrets engine API](/vault/api-docs/secret/pki) documentation.
